/* Copyright (c) 2025 Beijing Semidrive Technology Corporation
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/** *****************************************************************************************************
 * \file     Mcu_CkgenDrv.h                                                                            *
 * \brief    AUTOSAR 4.3.1 MCAL Mcu Driver                                                             *
 *                                                                                                      *
 * <table>                                                                                              *
 * <tr><th>Date           <th>Version                                                                   *
 * <tr><td>2023/08/02     <td>1.0.0                               *
 * </table>                                                                                             *
 *******************************************************************************************************/

#ifndef MCU_CKGENDRV_H
#define MCU_CKGENDRV_H
/********************************************************************************************************
 *                                      Include header files                                            *
 *******************************************************************************************************/
#include "Mcu_GeneralTypes.h"
/********************************************************************************************************
 *                                  Global Types definition                                             *
 *******************************************************************************************************/
typedef struct
{
    uint32 base;                /* ckgen base */
    Mcu_CkgenType type;         /* slice type (CKGEN_PCG_TYPE/CKGEN_BCG_TYPE/CKGEN_PLL_CG_TYPE/CKGEN_XTAL_CG_TYPE)*/
    uint32  typeIndex;          /* slice index */
    uint32 wdtTimeout;          /* wdtTimeout for xtal/pll ready */
    uint8  monIntRes;           /* interrupt status, 0-no err, other-error occured */
    uint32 realState;           /* real state */
} Mcu_CkgenMonReadyType;

typedef struct
{
    uint32 base;                /* ckgen base */
    Mcu_CkgenType sliceType;    /* slice type (CKGEN_IP_SLICE_TYPE/CKGEN_SF_BUS_SLICE_TYPE/MCU_BUS_SLICE/CKGEN_FS24M_TYPE/CKGEN_EXT_TYPE)*/
    uint32  typeIndex;          /* slice index*/
    uint32 sliceFreq;           /* Expected frequency */
    uint8  freqTolerantRat;     /* Threshold percentage */
    uint8  monIntRes;           /* interrupt status, 0-Frequency within threshold range, 1-Frequency out of threshold range, 0xFF-error occured */
    uint32 realFreq;            /* real frequency */
} Mcu_CkgenMonFreqType;

typedef struct
{
    uint32 base;                /* ckgen base */
    uint32 cqmIndex;            /* cqmIndex 0/1/2 */
    Mcu_CkgenType sliceType;    /* slice type */
    uint32 typeIndex;           /* slice index */
    uint8 dutyPercent;          /* dutyPercent */
    uint8 jitterPercent;        /* jitterPercent */
    uint8 dutyIntRes;           /* interrupt status, 0-duty within threshold range, 1-duty out of threshold range, 0xFF-error occured */
    uint8 jitterIntRes;         /* interrupt status, 0-jitter within threshold range, 1-jitter out of threshold range, 0xFF-error occured */
} Mcu_CkgenCqmType;

/********************************************************************************************************
 *                                  Global Function Declarations                                        *
 *******************************************************************************************************/
/** *****************************************************************************************************
 * \brief IP slice real frequency get by monitor.
 *
 * \verbatim
 * Syntax             : Mcu_ClkRateType Mcu_Ip_CkgenDrvIpMonGetRate(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : IP slice real frequency. UINT32_MAX means error.
 *
 * Description        : IP slice real frequency get by monitor.
 * \endverbatim
 *******************************************************************************************************/
Mcu_ClkRateType Mcu_Ip_CkgenDrvIpMonGetRate(const Mcu_ClkNodeType *clkPtr);

/** *****************************************************************************************************
 * \brief IP slice register frequency get by register caculated.
 *
 * \verbatim
 * Syntax             : Mcu_ClkRateType Mcu_Ip_CkgenDrvIpGetRate(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : IP slice register frequency, not real frequency
 *
 * Description        : IP slice register frequency get by register caculated.
 * \endverbatim
 *******************************************************************************************************/
Mcu_ClkRateType Mcu_Ip_CkgenDrvIpGetRate(const Mcu_ClkNodeType *clkPtr);
/** *****************************************************************************************************
 * \brief ip slice frequency set.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenDrvIpSetRate(const Mcu_ClkNodeType *clkPtr, Mcu_ClkRateType rate)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *                      rate - rate to set
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : errID
 *
 * Description        : ip slice frequency set.
 * \endverbatim
 * Traceability       : SW_SM006
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenDrvIpSetRate(const Mcu_ClkNodeType *clkPtr, Mcu_ClkRateType rate);

/** *****************************************************************************************************
 * \brief bus slice real frequency get by monitor.
 *
 * \verbatim
 * Syntax             : Mcu_ClkRateType Mcu_Ip_CkgenDrvBusMonGetRate(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : bus slice real frequency. UINT32_MAX means error.
 *
 * Description        : bus slice real frequency get by monitor.
 * \endverbatim
 *******************************************************************************************************/
Mcu_ClkRateType Mcu_Ip_CkgenDrvBusMonGetRate(const Mcu_ClkNodeType *clkPtr);

/** *****************************************************************************************************
 * \brief bus slice register frequency get by register caculated.
 *
 * \verbatim
 * Syntax             : Mcu_ClkRateType Mcu_Ip_CkgenDrvBusGetRate(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : bus slice register frequency, not real frequency
 *
 * Description        : bus slice register frequency get by register caculated.
 * \endverbatim
 *******************************************************************************************************/
Mcu_ClkRateType Mcu_Ip_CkgenDrvBusGetRate(const Mcu_ClkNodeType *clkPtr);

/** *****************************************************************************************************
 * \brief bus slice frequency set.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenDrvBusSetRate(const Mcu_ClkNodeType *clkPtr, Mcu_ClkRateType rate, Mcu_ClkBusRatioType postDiv)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *                      rate - rate to set
 *                      postDiv - cpu/axi/apb ratio, CKGEN_BUS_DIV_4_2_1: 0, CKGEN_BUS_DIV_2_2_1: 1
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : errID
 *
 * Description        : bus slice frequency set.
 * \endverbatim
 * Traceability       : SW_SM006
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenDrvBusSetRate(const Mcu_ClkNodeType *clkPtr, Mcu_ClkRateType rate,
        Mcu_ClkBusRatioType postDiv);

/** *****************************************************************************************************
 * \brief Clock gate turn on in run mode.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenDrvGatingEnable(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : errID
 *
 * Description        : Clock gate turn on in run mode.
 *
 * \endverbatim
 * Traceability       : SW_SM006
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenDrvGatingEnable(const Mcu_ClkNodeType *clkPtr);
/** *****************************************************************************************************
 * \brief Clock gate turn off in run mode.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenDrvGatingDisable(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : errID
 *
 * Description        : Clock gate turn off in run mode.
 *
 * \endverbatim
 * Traceability       : SW_SM006
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenDrvGatingDisable(const Mcu_ClkNodeType *clkPtr);

/** *****************************************************************************************************
 * \brief get the clock gate state(Amon) by monitor.
 *
 * \verbatim
 * Syntax             : uint8 Mcu_Ip_CkgenDrvMonGatingIsGated(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : clock gate state
 *
 * Description        : get the clock gate state in run mode.
 *                      return 1 means gated, 0 means active.
 *                      return 0xFFu means error occurred.
 *
 * \endverbatim
 * Traceability       : SW_SM006
 *******************************************************************************************************/
uint8 Mcu_Ip_CkgenDrvMonGatingIsGated(const Mcu_ClkNodeType *clkPtr);

/** *****************************************************************************************************
 * \brief get the clock gate state.
 *
 * \verbatim
 * Syntax             : uint8 Mcu_Ip_CkgenDrvGatingIsGated(const Mcu_ClkNodeType *clkPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : clkPtr - Pointer to clock node
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : clock gate state
 *
 * Description        : get the clock gate state in run mode.
 *                      return 1 means gated, 0 means active.
 *                      return 0xFFu means error occurred.
 *
 * \endverbatim
 * Traceability       : SW_SM006
 *******************************************************************************************************/
uint8 Mcu_Ip_CkgenDrvGatingIsGated(const Mcu_ClkNodeType *clkPtr);
/** *****************************************************************************************************
 * \brief This function used for enable/disable slice frequency monitor.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenDrvMonEnable(uint32 base, Mcu_CkgenType type, uint32 id, uint32 timeout, boolean enable)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - ckgen base
 *                      type - slice type
 *                      id - slice index
 *                      timeout - wdt timeout
 *                      enable - TRUE: enable, FALSE: disable
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : This function used for enable/disable slice frequency monitor.
 * \endverbatim
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenDrvMonEnable(uint32 base, Mcu_CkgenType type, uint32 id, uint32 timeout,
                                        boolean enable);
/** *****************************************************************************************************
 * \brief enable/disable dbgMon monitor.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenDrvDbgMonEnable(uint32 base, boolean enable)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - CKGEN base address
 *                      enable - TRUE/FALSE
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : enable/disable dbgMon monitor.
 *
 * \endverbatim
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenDrvDbgMonEnable(uint32 base, boolean enable);
/** *****************************************************************************************************
 * \brief config duty and jitter, enable/disable cqm monitor.
 *
 * \verbatim
 * Syntax             : void Mcu_Ip_CkgenDrvCqmEnable(uint32 base, uint32 cqmIndex, uint16 duty, uint16 jitter, boolean enable)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - CKGEN base address
 *                      duty - duty
 *                      jitter - jitter
 *                      enable - TRUE/FALSE
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        : config duty and jitter, enable/disable cqm monitor.
 *
 * \endverbatim
 *******************************************************************************************************/
void Mcu_Ip_CkgenDrvCqmEnable(uint32 base, uint32 cqmIndex, uint16 duty, uint16 jitter,
                              boolean enable);
/** *****************************************************************************************************
 * \brief This function monitor clock source ready and clock active.
 *
 * \verbatim
 * Syntax             : uint8 Mcu_Ip_CkgenMonDrvReady(Mcu_CkgenMonReadyType *ckgenMonReadyPtr)
 *
 * Service ID[hex]    : -
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : None
 *
 * Parameters (inout) : ckgenMonFreqPtr - Pointer to clock monitor node
 *                      typedef struct
                        {
                            uint32 base;
                            Mcu_ClkSliceType sliceType;(CKGEN_PCG_TYPE/CKGEN_BCG_TYPE/CKGEN_PLL_CG_TYPE/CKGEN_XTAL_CG_TYPE)
                            uint32 typeIndex;(slice id)
                            uint32 wdtTimeout;(wdtTimeout for xtal/pll ready)
                            uint8  monIntRes;(interrupt status, 0-no err, other-error occured)
                            uint32 realState;(real state)
                        } Mcu_CkgenMonReadyType;
 *
 * Parameters (out)   : None
 *
 * Return value       : clock monitor status
 *                      0 - the monitor status is ok
 *                      !0 - the monitor status is not ok
 *
 * Description        : This function monitor clock source ready and clock active.
 * \endverbatim
 * Traceability       : SWSR_MCU_049 SW_SM001
 *******************************************************************************************************/
uint8 Mcu_Ip_CkgenMonDrvReady(Mcu_CkgenMonReadyType *ckgenMonReadyPtr);

/** *****************************************************************************************************
 * \brief Monitor Slice freq high or low  interface.
 *
 * \verbatim
 * Syntax             : uint8 Mcu_Ip_CkgenDrvMonFreq(Mcu_CkgenMonFreqType *ckgenMonFreqPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : None
 *
 * Parameters (inout) : ckgenMonFreqPtr - Pointer to clock monitor node
 *                      typedef struct
                        {
                            uint32 base;
                            Mcu_CkgenType sliceType;(CKGEN_IP_SLICE_TYPE/CKGEN_SF_BUS_SLICE_TYPE/MCU_BUS_SLICE/CKGEN_FS24M_TYPE)
                            uint32 typeIndex;(slice id)
                            uint32 sliceFreq;(Expected frequency)
                            uint8  freqTolerantRat;(Threshold percentage)
                            uint8  monIntRes;(interrupt status, 0-Frequency within threshold range, 1-Frequency out of threshold range, 0xFF-error occured)
                            uint32 realFreq;(real frequency)
                        } Mcu_CkgenMonFreqType;
 *
 * Parameters (out)   : None
 *
 * Return value       : clock monitor status
 *                      0 - the monitor status of clock rate is ok
 *                      !0 - the monitor status of clock rate is not ok
 *
 * Description        : This function monitor clock rate.
 * \endverbatim
 *******************************************************************************************************/
uint8 Mcu_Ip_CkgenDrvMonFreq(Mcu_CkgenMonFreqType *ckgenMonFreqPtr);
/** *****************************************************************************************************
 * \brief Monitor DbgMon freq high or low  interface.
 *
 * \verbatim
 * Syntax             : uint8 Mcu_Ip_CkgenDrvDbgMonFreq(Mcu_CkgenMonFreqType *ckgenMonFreqPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : None
 *
 * Parameters (inout) : ckgenMonFreqPtr - Pointer to clock monitor node
 *                      typedef struct
                        {
                            uint32 base;
                            Mcu_CkgenType sliceType;(CKGEN_IP_SLICE_TYPE/CKGEN_SF_BUS_SLICE_TYPE/MCU_BUS_SLICE/CKGEN_EXT_TYPE)
                            uint32 typeIndex;(slice id)
                            uint32 sliceFreq;(Expected frequency)
                            uint8  freqTolerantRat;(Threshold percentage)
                            uint8  monIntRes;(interrupt status, 0-Frequency within threshold range, 1-Frequency out of threshold range, 0xFF-error occured)
                            uint32 realFreq;(real frequency)
                        } Mcu_CkgenMonFreqType;
 *
 * Parameters (out)   : None
 *
 * Return value       : clock monitor status
 *                      0 - the monitor status of clock rate is ok
 *                      !0 - the monitor status of clock rate is not ok
 *
 * Description        : This function monitor clock rate.
 * \endverbatim
 *******************************************************************************************************/
uint8 Mcu_Ip_CkgenDrvDbgMonFreq(Mcu_CkgenMonFreqType *ckgenMonFreqPtr);
/** *****************************************************************************************************
 * \brief Monitor clock duty and jitter interface.
 *
 * \verbatim
 * Syntax             : uint8 Mcu_Ip_CkgenDrvMonCqm(Mcu_CkgenCqmType *ckgenCqmPtr)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : None
 *
 * Parameters (inout) : ckgenCqmPtr - pointer to ckgencqm struct
 *                      typedef struct
 *                      {
 *                          uint32 base;                (ckgen base )
 *                          uint32 cqmIndex;            (cqmIndex 0/1/2)
 *                          Mcu_CkgenType sliceType;    (slice type )
 *                          uint32 typeIndex;           (slice index )
 *                          uint8 dutyPercent;          (dutyPercent )
 *                          uint8 jitterPercent;        (jitterPercent )
 *                          uint8 dutyIntRes;           (interrupt status, 0-duty within threshold range, 1-duty out of threshold range, 0xFF-error occured )
 *                          uint8 jitterIntRes;         (interrupt status, 0-jitter within threshold range, 1-jitter out of threshold range, 0xFF-error occured )
 *                      } Mcu_CkgenCqmType;
 *
 * Parameters (out)   : None
 *
 * Return value       :  0:Duty jtter Normal      1: Duty jtter out of range    0xFF-error occured
 *
 * Description        : Monitor clock duty and jitter interface
 * \endverbatim
 *******************************************************************************************************/
uint8 Mcu_Ip_CkgenDrvMonCqm(Mcu_CkgenCqmType *ckgenCqmPtr);

/** *****************************************************************************************************
 * \brief This function used for debug to pull clock nodes to pad to measure frequency.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_CkgenClockToPad(const Mcu_ClkNodeType *ckgenPtr, uint8 divNum)
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : ckgenPtr - clock note with type Mcu_CkgenNodeType defined in "Mcu_ClkCfgNode.h"
 *                      divNum - frequency division
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : errorId
 *                      E_OK for success and others for failure.
 *
 * Description        : This function used for debug to pull clock nodes to pad to measure frequency.
 *                      GPIO_A9/A10/A11 need MUX CKGEN_SF.CLK_DBG, GPIO_LA4/LA5/LA6 need MUX CKGEN_LPP.CLK_DBG
 * \endverbatim
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_CkgenClockToPad(const Mcu_ClkNodeType *ckgenPtr, uint8 divNum);
#endif /* MCU_CKGENDRV_H */
/* End of file */
